Skip to main content

SubcatchmentController

The SubcatchmentController manages SWMM subcatchment data and provides access to subcatchment attributes and simulation results.

Overview​

This controller handles subcatchment-related operations including retrieving attribute values, time series data, and simulation results. It integrates with Azure storage services to provide comprehensive subcatchment information for the SWMM model.

Data Sources​

  • Azure Table Storage:
    • SubCatchOutput table for subcatchment time series data
    • Runs table for run metadata
  • Azure Blob Storage:
    • swmm-output container for simulation results
  • Configuration: appsettings.json for connection string

Endpoints​

GET /api/subcatchment/attributes​

Retrieves time series data for a specific subcatchment attribute.

Query Parameters:

  • subcatchIndex (string): Subcatchment index
  • runDateTime (string): Simulation run datetime
  • subcatchResultValue (string): Attribute type (runoff, infiltration, etc.)

Response:

  • 200 OK: Returns array of attribute values
  • 404 Not Found: Subcatchment or data not found
  • 500 Internal Server Error: Processing error

Data Flow:

Table Query:

  • PartitionKey: {clientPartitionKey}_{scenario}_{runDateTime}
  • RowKey: {subcatchIndex}_{subcatchResultValue}

GET /api/subcatchment/attributeswithendtime​

Retrieves time series data for a subcatchment attribute with end time filtering.

Query Parameters:

  • subcatchIndex (string): Subcatchment index
  • runDateTime (string): Simulation run datetime
  • subcatchResultValue (string): Attribute type
  • endDateTime (string): End time for filtering

Response:

  • 200 OK: Returns filtered array of attribute values
  • 404 Not Found: Subcatchment or data not found
  • 500 Internal Server Error: Processing error

Data Flow:

Time Filtering Logic:

  • Calculates end index: (endDateTime - startDateTime).TotalMinutes / reportingTimeStep
  • Extracts array subset from index 0 to calculated end index
  • Handles timezone conversions and time step calculations

GET /api/subcatchment/results​

Retrieves simulation results for a specific subcatchment at a given timestep.

Query Parameters:

  • step (string): Simulation timestep
  • runDateTime (string): Simulation run datetime
  • subcatchmentIndex (string): Subcatchment index

Response:

  • 200 OK: Returns SwmmSubcatchmentResult object
  • 404 Not Found: Results not found
  • 500 Internal Server Error: Processing error

Data Flow:

Azure Storage Details​

Table Storage Schema​

SubCatchOutput Table:

  • PartitionKey: {clientPartitionKey}_{scenario}_{runDateTime}
  • RowKey: {subcatchIndex}_{subcatchResultValue}
  • Properties:
    • CSVSeries: Comma-separated time series data
    • Timestamp: Entity timestamp
    • ETag: Entity tag for concurrency

Runs Table:

  • PartitionKey: {clientPartitionKey}_{scenario}
  • RowKey: {runDateTime}
  • Properties: StartTime, EndTime, ReportingTimeStep, Status

Blob Storage Schema​

swmm-output Container:

{partitionKey}_{scenario}_{datetime}/
├── {step}
└── ...

Blob Content: JSON format containing SwmmResult object with subcatchment data

Data Models​

Subcatchment Result​

public class SwmmSubcatchmentResult
{
    public double Runoff { get; set; }
    public double Infiltration { get; set; }
    public double Evaporation { get; set; }
    public double SnowDepth { get; set; }
    public double Quality { get; set; }
}

Subcatchment Output Entity​

public class SubCatchOutputEntity : ITableEntity
{
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public string CSVSeries { get; set; }
    public DateTimeOffset Timestamp { get; set; }
    public ETag ETag { get; set; }
}

Configuration​

Required Settings:

{
  "Values": {
    "CloudStorageConnectionString": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net"
  }
}

Error Handling​

  • Storage Errors: Logged to Azure Table Storage
  • Missing Data: Returns null or empty arrays
  • Invalid Parameters: Graceful parameter validation
  • Time Processing: Handles timezone and format issues
  • Data Parsing: Handles malformed CSV data

Performance Considerations​

  • Memory Management: Uses memory streams for blob operations
  • Data Parsing: Efficient CSV string parsing
  • Time Calculations: Optimized time index calculations
  • Caching: No built-in caching (consider for frequently accessed data)
  • Error Recovery: Graceful handling of missing data

Dependencies​

  • Azure.Storage.Blobs
  • Azure.Data.Tables
  • GqcStorage1 (Storage utilities)
  • SwmmModels (Data models)
  • System.Text.Json

Common Subcatchment Attributes​

  • Runoff: Surface runoff volume
  • Infiltration: Infiltration rate
  • Evaporation: Evaporation rate
  • SnowDepth: Snow depth
  • Quality: Water quality parameters
  • ImperviousRunoff: Impervious area runoff
  • PerviousRunoff: Pervious area runoff

Time Series Processing​

  • CSV Parsing: Converts comma-separated values to double arrays
  • Time Indexing: Calculates array indices from timestamps
  • Time Windows: Supports start/end time filtering
  • Reporting Steps: Uses reporting time step from run configuration
  • Data Validation: Handles null/missing values

Usage Examples​

Get Subcatchment Attributes:

GET /api/subcatchment/attributes?subcatchIndex=0&runDateTime=2023-11-16T00:00:00-05:00&subcatchResultValue=0

Get Attributes with End Time:

GET /api/subcatchment/attributeswithendtime?subcatchIndex=0&runDateTime=2023-11-16T00:00:00-05:00&subcatchResultValue=0&endDateTime=2023-11-16T12:00:00-05:00

Get Subcatchment Results:

GET /api/subcatchment/results?step=15&runDateTime=2023-11-16T00:00:00-05:00&subcatchmentIndex=0

Response Examples​

Attribute Values Response:

[1.2, 1.5, 1.8, 2.1, 1.9, 1.6, 1.3, 1.1, 0.9, 0.7]

Subcatchment Result Response:

{
  "runoff": 0.5,
  "infiltration": 0.3,
  "evaporation": 0.1,
  "snowDepth": 0.0,
  "quality": 0.8
}

Data Quality Considerations​

  • Time Alignment: Ensures proper time step alignment
  • Missing Data: Handles gaps in time series
  • Data Validation: Validates subcatchment data consistency
  • Unit Conversion: Maintains proper units throughout
  • Error Recovery: Graceful handling of data corruption

Limitations​

  • Single Subcatchment: Returns data for one subcatchment at a time
  • No Aggregation: No built-in aggregation across multiple subcatchments
  • Limited Filtering: Basic time window filtering only
  • No Caching: Direct database queries each time
  • Synchronous: Some operations are synchronous